<!DOCTYPE html><html><head><title>Koa - next generation web framework for node.js</title>


<style>

* {
  -webkit-box-sizing: border-box;
}

body, html {
  margin: 0;
  padding: 0;
  height: 100%;
}

body {
  font: 17px/1.5 "Lucida Grande", "Lucida Sans Unicode", Helvetica, Arial, Verdana, sans-serif;
  background: white;
  margin: 0;
  color: #33333d;
  overflow-y: scroll;
  overflow-x: hidden;
}

a {
  color: #33a0c0;
}

section {
  min-height: 50%;
}

section:not(:last-child) {
  border-bottom: 1px solid #eee;
}

section:not(#top) {
  padding: 150px 100px;
  text-align: center;
}

pre {
  background: white;
  border-top: 1px solid #eee;
  border-bottom: 1px solid #eee;
  padding: 25px;
  font-size: .9em;
  font-family: monospace;
  overflow-x: auto;
}

.content img {
  width: 100%;
}

p {
  font-weight: 300;
  font-family: "Lucida Grande", "Lucida Sans Unicode", Helvetica, Arial, Verdana, sans-serif;
}

code {
  font-family: monospace;
  font-size: .9em;
}

h1 {
  margin-top: 0;
  font-size: 2em;
}

h1:not(:first-child) {
  margin-top: 50px;
}

h2 {
  margin-top: 80px;
  font-size: 1.2em;
}

h3 {
  margin-top: 40px;
  font-size: 1em;
}

ul li {
  font-size: .8em;
}

section:nth-child(2n) {
  background: #fdfdfd;
  box-shadow: inset 0 1px 0 0 white;
}

.content {
  margin: 0 auto;
  max-width: 750px;
  text-align: left;
}

#top {
  height: 100%;
}

#heading {
  -webkit-user-select: none;
  position: absolute;
  top: 50%;
  margin-top: -150px;
  text-align: center;
  width: 100%;
}

#logo {
  font: 150px 'Italiana', sans-serif;
  text-transform: lowercase;
}

#tagline {
  font-size: 16px;
}

#menu {
  position: fixed;
  top: 35px;
  right: 30px;
  z-index: 50;
}

#menu:hover ul {
  display: block;
}

#menu a {
  color: inherit;
}

#menu a#toggle {
  position: absolute;
  top: 0;
  right: 0;
  padding: 5px;
  background: rgba(255,255,255,.9);
  border-radius: 2px;
  border: 1px solid transparent;
  z-index: 5;
}

#menu:hover a#toggle {
  border: 1px solid #efefef;
  border-bottom: none;
}

#menu ul {
  display: none;
  position: absolute;
  top: 35px;
  right: 0;
  margin: 0;
  border: 1px solid #efefef;
  border-bottom: 1px solid #ddd;
  border-radius: 2px;
  padding: 25px;
  background: rgba(255,255,255,.95);
  box-shadow: 0 1px 3px 0 #eee;
}

#menu ul li {
  list-style: none;
}

#menu ul li a {
  display: block;
  text-decoration: none;
  padding: 3px 0;
}

#menu ul li a:hover {
  text-decoration: underline;
}

@media screen and (max-width: 700px) {
  section:not(#top) {
    padding: 50px 25px;
  }

  #heading {
    margin-top: -75px;
  }

  #logo {
    font-size: 75px;
  }

  #tagline {
    font-size: 12px;
  }
}

@media screen and (max-width: 500px) {
  body {
    font-size: 13px;
  }
}


 [class^="icon-"]:before, [class*=" icon-"]:before {
  font-family: "slate";
  font-style: normal;
  font-weight: normal;
  speak: none;

  display: inline-block;
  text-decoration: inherit;
  width: 1em;
  margin-right: .2em;
  text-align: center;
  /* opacity: .8; */

  /* For safety - reset parent styles, that can break glyph codes*/
  font-variant: normal;
  text-transform: none;

  /* fix buttons height, for twitter bootstrap */
  line-height: 1em;

  /* Animation center compensation - margins should be symmetric */
  /* remove if not needed */
  margin-left: .2em;

  /* you can be more comfortable with increased icons size */
  /* font-size: 120%; */

  /* Uncomment for 3D effect */
  /* text-shadow: 1px 1px 1px rgba(127, 127, 127, 0.3); */
}

.icon-cancel:before { content: '\e803'; } /* '' */
.icon-menu-1:before { content: '\e811'; } /* '' */
.icon-plus:before { content: '\e804'; } /* '' */
.icon-plus-circled:before { content: '\e805'; } /* '' */
.icon-minus:before { content: '\e800'; } /* '' */
.icon-minus-circled:before { content: '\e806'; } /* '' */
.icon-attention-alt:before { content: '\e809'; } /* '' */
.icon-attention:before { content: '\e808'; } /* '' */
.icon-attention-circled:before { content: '\e80a'; } /* '' */
.icon-cancel-circled:before { content: '\e802'; } /* '' */
.icon-cog:before { content: '\e807'; } /* '' */
.icon-resize-full:before { content: '\e810'; } /* '' */
.icon-signal:before { content: '\e80b'; } /* '' */
.icon-smile:before { content: '\e80c'; } /* '' */
.icon-frown:before { content: '\e80d'; } /* '' */
.icon-meh:before { content: '\e80e'; } /* '' */
.icon-github:before { content: '\e80f'; } /* '' */
.icon-menu:before { content: '\e801'; } /* '' */
</style>
<meta name="viewport" content="user-scalable=no, width=device-width, initial-scale=1.0, maximum-scale=1.0"></head><body><section id="top"><div id="menu"><a id="toggle" href="index.html#"><i class="icon-menu"></i></a><ul><li><a href="index.html#introduction">Introduction</a></li><li><a href="index.html#application">Application</a></li><li><a href="index.html#context">Context</a></li><li><a href="index.html#request">Request</a></li><li><a href="index.html#response">Response</a></li><li><a href="index.html#links">Links</a></li></ul></div><div id="heading"><div id="logo">Koa</div><div id="tagline">next generation web framework for node.js</div></div></section><section><div class="content"><h1 id="introduction">Introduction</h1><p>Koa is a new web framework designed by the team behind Express,
which aims to be a smaller, more expressive, and more robust foundation
for web applications and APIs. Through leveraging generators Koa allows you
to ditch callbacks and greatly increase error-handling. Koa does not bundle any
middleware within core, and provides an elegant suite of methods that make
writing servers fast and enjoyable.
</p></div></section><section><div class="content"><h1 id="installation">Installation</h1>
<p>Koa works out of the box with recent versions of Node. To use Koa with 0.11.x you must use the <code>--harmony</code> or <code>--harmony-generators</code> flag.</p>
<pre><code class="lang-bash">$ npm install koa
$ node app.js</code></pre>
<h1 id="application">Application</h1>
<p>  A Koa application is an object containing an array of middleware generator functions
  which are composed and executed in a stack-like manner upon request. Koa is similar to many
  other middleware systems that you may have encountered such as Ruby&#39;s Rack, Connect, and so on -
  however a key design decision was made to provide high level &quot;sugar&quot; at the otherwise low-level
  middleware layer. This improves interoperability, robustness, and makes writing middleware much
  more enjoyable.</p>
<p>  This includes methods for common tasks like content-negotiation, cache freshness, proxy support, and redirection
  among others. Despite supplying a reasonably large number of helpful methods Koa maintains a small footprint, as
  no middleware are bundled.</p>
<p>  The obligatory hello world application:</p>
<pre><code class="lang-js">var koa = require(&#39;koa&#39;);
var app = koa();

app.use(function *(){
  this.body = &#39;Hello World&#39;;
});

app.listen(3000);</code></pre>
<h2 id="cascading">Cascading</h2>
<p>  Koa middleware cascade in a more traditional way as you may be used to with similar tools -
  this was previously difficult to make user friendly with node&#39;s use of callbacks.
  However with generators we can achieve &quot;true&quot; middleware. Contrasting Connect&#39;s implementation which
  simply passes control through series of functions until one returns, Koa yields &quot;downstream&quot;, then
  control flows back &quot;upstream&quot;.</p>
<p>  The following example responds with &quot;Hello World&quot;, however first the request flows through
  the <code>x-response-time</code> and <code>logging</code> middleware to mark when the request started, then continue
  to yield control through the response middleware. When a middleware invokes <code>yield next</code>
  the function suspends and passes control to the next middleware defined. After there are no more
  middleware to execute downstream, the stack will unwind and each middleware is resumed to perform
  its upstream behaviour.</p>
<pre><code class="lang-js">var koa = require(&#39;koa&#39;);
var app = koa();

// x-response-time

app.use(function *(next){
  var start = new Date;
  yield next;
  var ms = new Date - start;
  this.set(&#39;X-Response-Time&#39;, ms + &#39;ms&#39;);
});

// logger

app.use(function *(next){
  var start = new Date;
  yield next;
  var ms = new Date - start;
  console.log(&#39;%s %s - %s&#39;, this.method, this.url, ms);
});

// response

app.use(function *(){
  this.body = &#39;Hello World&#39;;
});

app.listen(3000);</code></pre>
<h2 id="settings">Settings</h2>
<p>  Application settings are properties on the <code>app</code> instance, currently
  the following are supported:</p>
<ul>
<li><code>app.name</code> optionally give your application a name</li>
<li><code>app.env</code> defaulting to the <strong>NODE_ENV</strong> or &quot;development&quot;</li>
<li><code>app.proxy</code> when true proxy header fields will be trusted</li>
<li><code>app.subdomainOffset</code> offset of <code>.subdomains</code> to ignore [2]</li>
</ul>
<h2 id="app-listen-">app.listen(...)</h2>
<p>  A Koa application is not a 1-to-1 representation of a HTTP server.
  One or more Koa applications may be mounted together to form larger
  applications with a single HTTP server.</p>
<p>  Create and return an HTTP server, passing the given arguments to
  <code>Server#listen()</code>. These arguments are documented on <a href="http://nodejs.org/api/http.html#http_server_listen_port_hostname_backlog_callback">nodejs.org</a>. The following is a useless Koa application bound to port <code>3000</code>:</p>
<pre><code class="lang-js">var koa = require(&#39;koa&#39;);
var app = koa();
app.listen(3000);</code></pre>
<p>  The <code>app.listen(...)</code> method is simply sugar for the following:</p>
<pre><code class="lang-js">var http = require(&#39;http&#39;);
var koa = require(&#39;koa&#39;);
var app = koa();
http.createServer(app.callback()).listen(3000);</code></pre>
<p>  This means you can spin up the same application as both HTTP and HTTPS
  or on multiple addresses:</p>
<pre><code class="lang-js">var http = require(&#39;http&#39;);
var koa = require(&#39;koa&#39;);
var app = koa();
http.createServer(app.callback()).listen(3000);
http.createServer(app.callback()).listen(3001);</code></pre>
<h2 id="app-callback-">app.callback()</h2>
<p>  Return a callback function suitable for the <code>http.createServer()</code>
  method to handle a request.
  You may also use this callback function to mount your koa app in a
  Connect/Express app.</p>
<h2 id="app-use-function-">app.use(function)</h2>
<p>  Add the given middleware function to this application. See <a href="https://github.com/koajs/koa/wiki#middleware">Middleware</a> for
  more information.</p>
<h2 id="app-keys-">app.keys=</h2>
<p> Set signed cookie keys.</p>
<p> These are passed to <a href="https://github.com/jed/keygrip">KeyGrip</a>,
 however you may also pass your own <code>KeyGrip</code> instance. For
 example the following are acceptable:</p>
<pre><code class="lang-js">app.keys = [&#39;im a newer secret&#39;, &#39;i like turtle&#39;];
app.keys = new KeyGrip([&#39;im a newer secret&#39;, &#39;i like turtle&#39;], &#39;sha256&#39;);</code></pre>
<p>  These keys may be rotated and are used when signing cookies
  with the <code>{ signed: true }</code> option:</p>
<pre><code class="lang-js">this.cookies.set(&#39;name&#39;, &#39;tobi&#39;, { signed: true });</code></pre>
<h2 id="app-context">app.context</h2>
<p>  The recommended namespace to extend with information that&#39;s useful
  throughout the lifetime of your application, as opposed to a per request basis.</p>
<pre><code class="lang-js">app.context.db = db();</code></pre>
<h2 id="error-handling">Error Handling</h2>
<p>  By default outputs all errors to stderr unless <strong>NODE_ENV</strong> is &quot;test&quot;. To perform custom error-handling logic such as centralized logging you
  can add an &quot;error&quot; event listener:</p>
<pre><code class="lang-js">app.on(&#39;error&#39;, function(err){
  log.error(&#39;server error&#39;, err);
});</code></pre>
<p>  If an error in the req/res cycle and it is <em>not</em> possible to respond to the client, the <code>Context</code> instance is also passed:</p>
<pre><code class="lang-js">app.on(&#39;error&#39;, function(err, ctx){
  log.error(&#39;server error&#39;, err, ctx);
});</code></pre>
<p>  When an error occurs <em>and</em> it is still possible to respond to the client, aka no data has been written to the socket, Koa will respond
  appropriately with a 500 &quot;Internal Server Error&quot;. In either case
  an app-level &quot;error&quot; is emitted for logging purposes.</p>
</div></section><section><div class="content"><h1 id="context">Context</h1>
<p>  A Koa Context encapsulates node&#39;s <code>request</code> and <code>response</code> objects
  into a single object which provides many helpful methods for writing
  web applications and APIs.
  These operations are used so frequently in HTTP server development
  that they are added at this level instead of a higher level framework,
  which would force middleware to re-implement this common functionality.</p>
<p>  A <code>Context</code> is created <em>per</em> request, and is referenced in middleware
  as the receiver, or the <code>this</code> identifier, as shown in the following
  snippet:</p>
<pre><code class="lang-js">app.use(function *(){
  this; // is the Context
  this.request; // is a koa Request
  this.response; // is a koa Response
});</code></pre>
<p>  Many of the context&#39;s accessors and methods simply delegate to their <code>ctx.request</code> or <code>ctx.response</code>
  equivalents for convenience, and are otherwise identical. For example <code>ctx.type</code> and <code>ctx.length</code>
  delegate to the <code>response</code> object, and <code>ctx.path</code> and <code>ctx.method</code> delegate to the <code>request</code>.</p>
<h2 id="api">API</h2>
<p>  <code>Context</code> specific methods and accessors.</p>
<h3 id="ctx-req">ctx.req</h3>
<p>  Node&#39;s <code>request</code> object.</p>
<h3 id="ctx-res">ctx.res</h3>
<p>  Node&#39;s <code>response</code> object.</p>
<p>  Bypassing Koa&#39;s response handling is <strong>not supported</strong>. Avoid using the following node properties:</p>
<ul>
<li><code>res.statusCode</code></li>
<li><code>res.writeHead()</code></li>
<li><code>res.write()</code></li>
<li><code>res.end()</code></li>
</ul>
<h3 id="ctx-request">ctx.request</h3>
<p>  A koa <code>Request</code> object.</p>
<h3 id="ctx-response">ctx.response</h3>
<p>  A koa <code>Response</code> object.</p>
<h3 id="ctx-state">ctx.state</h3>
<p>  The recommended namespace for passing information through middleware and to your frontend views.</p>
<pre><code class="lang-js">this.state.user = yield User.find(id);</code></pre>
<h3 id="ctx-app">ctx.app</h3>
<p>  Application instance reference.</p>
<h3 id="ctx-cookies-get-name-options-">ctx.cookies.get(name, [options])</h3>
<p>  Get cookie <code>name</code> with <code>options</code>:</p>
<ul>
<li><code>signed</code> the cookie requested should be signed</li>
</ul>
<p>koa uses the <a href="https://github.com/jed/cookies">cookies</a> module where options are simply passed.</p>
<h3 id="ctx-cookies-set-name-value-options-">ctx.cookies.set(name, value, [options])</h3>
<p>  Set cookie <code>name</code> to <code>value</code> with <code>options</code>:</p>
<ul>
<li><code>signed</code> sign the cookie value</li>
<li><code>expires</code> a <code>Date</code> for cookie expiration</li>
<li><code>path</code> cookie path, <code>/&#39;</code> by default</li>
<li><code>domain</code> cookie domain</li>
<li><code>secure</code> secure cookie</li>
<li><code>httpOnly</code> server-accessible cookie, <strong>true</strong> by default</li>
</ul>
<p>koa uses the <a href="https://github.com/jed/cookies">cookies</a> module where options are simply passed.</p>
<h3 id="ctx-throw-msg-status-properties-">ctx.throw([msg], [status], [properties])</h3>
<p>  Helper method to throw an error with a <code>.status</code> property
  defaulting to <code>500</code> that will allow Koa to respond appropriately.
  The following combinations are allowed:</p>
<pre><code class="lang-js">this.throw(403);
this.throw(&#39;name required&#39;, 400);
this.throw(400, &#39;name required&#39;);
this.throw(&#39;something exploded&#39;);</code></pre>
<p>  For example <code>this.throw(&#39;name required&#39;, 400)</code> is equivalent to:</p>
<pre><code class="lang-js">var err = new Error(&#39;name required&#39;);
err.status = 400;
throw err;</code></pre>
<p>  Note that these are user-level errors and are flagged with
  <code>err.expose</code> meaning the messages are appropriate for
  client responses, which is typically not the case for
  error messages since you do not want to leak failure
  details.</p>
<p>  You may optionally pass a <code>properties</code> object which is merged into the error as-is, useful for decorating machine-friendly errors which are reported to the requester upstream.</p>
<pre><code class="lang-js">this.throw(401, &#39;access_denied&#39;, { user: user });
this.throw(&#39;access_denied&#39;, { user: user });</code></pre>
<p>koa uses <a href="https://github.com/jshttp/http-errors">http-errors</a> to create errors.</p>
<h3 id="ctx-assert-value-msg-status-properties-">ctx.assert(value, [msg], [status], [properties])</h3>
<p>  Helper method to throw an error similar to <code>.throw()</code>
  when <code>!value</code>. Similar to node&#39;s <a href="http://nodejs.org/api/assert.html">assert()</a>
  method.</p>
<pre><code class="lang-js">this.assert(this.state.user, 401, &#39;User not found. Please login!&#39;);</code></pre>
<p>koa uses <a href="https://github.com/jshttp/http-assert">http-assert</a> for assertions.</p>
<h3 id="ctx-respond">ctx.respond</h3>
<p>  To bypass Koa&#39;s built-in response handling, you may explicitly set <code>this.respond = false;</code>. Use this if you want to write to the raw <code>res</code> object instead of letting Koa handle the response for you.</p>
<p>  Note that using this is <strong>not</strong> supported by Koa. This may break intended functionality of Koa middleware and Koa itself. Using this property is considered a hack and is only a convenience to those wishing to use traditional <code>fn(req, res)</code> functions and middleware within Koa.</p>
<h2 id="request-aliases">Request aliases</h2>
<p>  The following accessors and alias <a href="index.html#request">Request</a> equivalents:</p>
<ul>
<li><code>ctx.header</code></li>
<li><code>ctx.headers</code></li>
<li><code>ctx.method</code></li>
<li><code>ctx.method=</code></li>
<li><code>ctx.url</code></li>
<li><code>ctx.url=</code></li>
<li><code>ctx.originalUrl</code></li>
<li><code>ctx.origin</code></li>
<li><code>ctx.href</code></li>
<li><code>ctx.path</code></li>
<li><code>ctx.path=</code></li>
<li><code>ctx.query</code></li>
<li><code>ctx.query=</code></li>
<li><code>ctx.querystring</code></li>
<li><code>ctx.querystring=</code></li>
<li><code>ctx.host</code></li>
<li><code>ctx.hostname</code></li>
<li><code>ctx.fresh</code></li>
<li><code>ctx.stale</code></li>
<li><code>ctx.socket</code></li>
<li><code>ctx.protocol</code></li>
<li><code>ctx.secure</code></li>
<li><code>ctx.ip</code></li>
<li><code>ctx.ips</code></li>
<li><code>ctx.subdomains</code></li>
<li><code>ctx.is()</code></li>
<li><code>ctx.accepts()</code></li>
<li><code>ctx.acceptsEncodings()</code></li>
<li><code>ctx.acceptsCharsets()</code></li>
<li><code>ctx.acceptsLanguages()</code></li>
<li><code>ctx.get()</code></li>
</ul>
<h2 id="response-aliases">Response aliases</h2>
<p>  The following accessors and alias <a href="index.html#response">Response</a> equivalents:</p>
<ul>
<li><code>ctx.body</code></li>
<li><code>ctx.body=</code></li>
<li><code>ctx.status</code></li>
<li><code>ctx.status=</code></li>
<li><code>ctx.message</code></li>
<li><code>ctx.message=</code></li>
<li><code>ctx.length=</code></li>
<li><code>ctx.length</code></li>
<li><code>ctx.type=</code></li>
<li><code>ctx.type</code></li>
<li><code>ctx.headerSent</code></li>
<li><code>ctx.redirect()</code></li>
<li><code>ctx.attachment()</code></li>
<li><code>ctx.set()</code></li>
<li><code>ctx.append()</code></li>
<li><code>ctx.remove()</code></li>
<li><code>ctx.lastModified=</code></li>
<li><code>ctx.etag=</code></li>
</ul>
</div></section><section><div class="content"><h1 id="request">Request</h1>
<p>  A Koa <code>Request</code> object is an abstraction on top of node&#39;s vanilla request object,
  providing additional functionality that is useful for every day HTTP server
  development.</p>
<h2 id="api">API</h2>
<h3 id="request-header">request.header</h3>
<p> Request header object.</p>
<h3 id="request-headers">request.headers</h3>
<p> Request header object. Alias as <code>request.header</code>.</p>
<h3 id="request-method">request.method</h3>
<p>  Request method.</p>
<h3 id="request-method-">request.method=</h3>
<p>  Set request method, useful for implementing middleware
  such as <code>methodOverride()</code>.</p>
<h3 id="request-length">request.length</h3>
<p>  Return request Content-Length as a number when present, or <code>undefined</code>.</p>
<h3 id="request-url">request.url</h3>
<p>  Get request URL.</p>
<h3 id="request-url-">request.url=</h3>
<p>  Set request URL, useful for url rewrites.</p>
<h3 id="request-originalurl">request.originalUrl</h3>
<p>  Get request original URL.</p>
<h3 id="request-origin">request.origin</h3>
<p>  Get origin of URL, include <code>protocol</code> and <code>host</code>.</p>
<pre><code class="lang-js">this.request.origin
// =&gt; http://example.com</code></pre>
<h3 id="request-href">request.href</h3>
<p>  Get full request URL, include <code>protocol</code>, <code>host</code> and <code>url</code>.</p>
<pre><code class="lang-js">this.request.href
// =&gt; http://example.com/foo/bar?q=1</code></pre>
<h3 id="request-path">request.path</h3>
<p>  Get request pathname.</p>
<h3 id="request-path-">request.path=</h3>
<p>  Set request pathname and retain query-string when present.</p>
<h3 id="request-querystring">request.querystring</h3>
<p>  Get raw query string void of <code>?</code>.</p>
<h3 id="request-querystring-">request.querystring=</h3>
<p>  Set raw query string.</p>
<h3 id="request-search">request.search</h3>
<p>  Get raw query string with the <code>?</code>.</p>
<h3 id="request-search-">request.search=</h3>
<p>  Set raw query string.</p>
<h3 id="request-host">request.host</h3>
<p>  Get host (hostname:port) when present. Supports <code>X-Forwarded-Host</code>
  when <code>app.proxy</code> is <strong>true</strong>, otherwise <code>Host</code> is used.</p>
<h3 id="request-hostname">request.hostname</h3>
<p>  Get hostname when present. Supports <code>X-Forwarded-Host</code>
  when <code>app.proxy</code> is <strong>true</strong>, otherwise <code>Host</code> is used.</p>
<h3 id="request-type">request.type</h3>
<p>  Get request <code>Content-Type</code> void of parameters such as &quot;charset&quot;.</p>
<pre><code class="lang-js">var ct = this.request.type;
// =&gt; &quot;image/png&quot;</code></pre>
<h3 id="request-charset">request.charset</h3>
<p>  Get request charset when present, or <code>undefined</code>:</p>
<pre><code class="lang-js">this.request.charset
// =&gt; &quot;utf-8&quot;</code></pre>
<h3 id="request-query">request.query</h3>
<p>  Get parsed query-string, returning an empty object when no
  query-string is present. Note that this getter does <em>not</em>
  support nested parsing.</p>
<p>  For example &quot;color=blue&amp;size=small&quot;:</p>
<pre><code class="lang-js">{
  color: &#39;blue&#39;,
  size: &#39;small&#39;
}</code></pre>
<h3 id="request-query-">request.query=</h3>
<p>  Set query-string to the given object. Note that this
  setter does <em>not</em> support nested objects.</p>
<pre><code class="lang-js">this.query = { next: &#39;/login&#39; };</code></pre>
<h3 id="request-fresh">request.fresh</h3>
<p>  Check if a request cache is &quot;fresh&quot;, aka the contents have not changed. This
  method is for cache negotiation between <code>If-None-Match</code> / <code>ETag</code>, and <code>If-Modified-Since</code> and <code>Last-Modified</code>. It should be referenced after setting one or more of these response headers.</p>
<pre><code class="lang-js">// freshness check requires status 20x or 304
this.status = 200;
this.set(&#39;ETag&#39;, &#39;123&#39;);

// cache is ok
if (this.fresh) {
  this.status = 304;
  return;
}

// cache is stale
// fetch new data
this.body = yield db.find(&#39;something&#39;);</code></pre>
<h3 id="request-stale">request.stale</h3>
<p>  Inverse of <code>request.fresh</code>.</p>
<h3 id="request-protocol">request.protocol</h3>
<p>  Return request protocol, &quot;https&quot; or &quot;http&quot;. Supports <code>X-Forwarded-Proto</code>
  when <code>app.proxy</code> is <strong>true</strong>.</p>
<h3 id="request-secure">request.secure</h3>
<p>  Shorthand for <code>this.protocol == &quot;https&quot;</code> to check if a request was
  issued via TLS.</p>
<h3 id="request-ip">request.ip</h3>
<p>  Request remote address. Supports <code>X-Forwarded-For</code> when <code>app.proxy</code>
  is <strong>true</strong>.</p>
<h3 id="request-ips">request.ips</h3>
<p>  When <code>X-Forwarded-For</code> is present and <code>app.proxy</code> is enabled an array
  of these ips is returned, ordered from upstream -&gt; downstream. When disabled
  an empty array is returned.</p>
<h3 id="request-subdomains">request.subdomains</h3>
<p>  Return subdomains as an array.</p>
<p>  Subdomains are the dot-separated parts of the host before the main domain of
  the app. By default, the domain of the app is assumed to be the last two
  parts of the host. This can be changed by setting <code>app.subdomainOffset</code>.</p>
<p>  For example, if the domain is &quot;tobi.ferrets.example.com&quot;:
  If <code>app.subdomainOffset</code> is not set, this.subdomains is <code>[&quot;ferrets&quot;, &quot;tobi&quot;]</code>.
  If <code>app.subdomainOffset</code> is 3, this.subdomains is <code>[&quot;tobi&quot;]</code>.</p>
<h3 id="request-is-types-">request.is(types...)</h3>
<p>  Check if the incoming request contains the &quot;Content-Type&quot;
  header field, and it contains any of the give mime <code>type</code>s.
  If there is no request body, <code>undefined</code> is returned.
  If there is no content type, or the match fails <code>false</code> is returned.
  Otherwise, it returns the matching content-type.</p>
<pre><code class="lang-js">// With Content-Type: text/html; charset=utf-8
this.is(&#39;html&#39;); // =&gt; &#39;html&#39;
this.is(&#39;text/html&#39;); // =&gt; &#39;text/html&#39;
this.is(&#39;text/*&#39;, &#39;text/html&#39;); // =&gt; &#39;text/html&#39;

// When Content-Type is application/json
this.is(&#39;json&#39;, &#39;urlencoded&#39;); // =&gt; &#39;json&#39;
this.is(&#39;application/json&#39;); // =&gt; &#39;application/json&#39;
this.is(&#39;html&#39;, &#39;application/*&#39;); // =&gt; &#39;application/json&#39;

this.is(&#39;html&#39;); // =&gt; false</code></pre>
<p>  For example if you want to ensure that
  only images are sent to a given route:</p>
<pre><code class="lang-js">if (this.is(&#39;image/*&#39;)) {
  // process
} else {
  this.throw(415, &#39;images only!&#39;);
}</code></pre>
<h3 id="content-negotiation">Content Negotiation</h3>
<p>  Koa&#39;s <code>request</code> object includes helpful content negotiation utilities powered by <a href="http://github.com/expressjs/accepts">accepts</a> and <a href="https://github.com/federomero/negotiator">negotiator</a>. These utilities are:</p>
<ul>
<li><code>request.accepts(types)</code></li>
<li><code>request.acceptsEncodings(types)</code></li>
<li><code>request.acceptsCharsets(charsets)</code></li>
<li><code>request.acceptsLanguages(langs)</code></li>
</ul>
<p>If no types are supplied, <strong>all</strong> acceptable types are returned.</p>
<p>If multiple types are supplied, the best match will be returned. If no matches are found, a <code>false</code> is returned, and you should send a <code>406 &quot;Not Acceptable&quot;</code> response to the client.</p>
<p>In the case of missing accept headers where any type is acceptable, the first type will be returned. Thus, the order of types you supply is important.</p>
<h3 id="request-accepts-types-">request.accepts(types)</h3>
<p>  Check if the given <code>type(s)</code> is acceptable, returning the best match when true, otherwise <code>false</code>. The <code>type</code> value may be one or more mime type string
  such as &quot;application/json&quot;, the extension name
  such as &quot;json&quot;, or an array <code>[&quot;json&quot;, &quot;html&quot;, &quot;text/plain&quot;]</code>.</p>
<pre><code class="lang-js">// Accept: text/html
this.accepts(&#39;html&#39;);
// =&gt; &quot;html&quot;

// Accept: text/*, application/json
this.accepts(&#39;html&#39;);
// =&gt; &quot;html&quot;
this.accepts(&#39;text/html&#39;);
// =&gt; &quot;text/html&quot;
this.accepts(&#39;json&#39;, &#39;text&#39;);
// =&gt; &quot;json&quot;
this.accepts(&#39;application/json&#39;);
// =&gt; &quot;application/json&quot;

// Accept: text/*, application/json
this.accepts(&#39;image/png&#39;);
this.accepts(&#39;png&#39;);
// =&gt; false

// Accept: text/*;q=.5, application/json
this.accepts([&#39;html&#39;, &#39;json&#39;]);
this.accepts(&#39;html&#39;, &#39;json&#39;);
// =&gt; &quot;json&quot;

// No Accept header
this.accepts(&#39;html&#39;, &#39;json&#39;);
// =&gt; &quot;html&quot;
this.accepts(&#39;json&#39;, &#39;html&#39;);
// =&gt; &quot;json&quot;</code></pre>
<p>  You may call <code>this.accepts()</code> as many times as you like,
  or use a switch:</p>
<pre><code class="lang-js">switch (this.accepts(&#39;json&#39;, &#39;html&#39;, &#39;text&#39;)) {
  case &#39;json&#39;: break;
  case &#39;html&#39;: break;
  case &#39;text&#39;: break;
  default: this.throw(406, &#39;json, html, or text only&#39;);
}</code></pre>
<h3 id="request-acceptsencodings-encodings-">request.acceptsEncodings(encodings)</h3>
<p>  Check if <code>encodings</code> are acceptable, returning the best match when true, otherwise <code>false</code>. Note that you should include <code>identity</code> as one of the encodings!</p>
<pre><code class="lang-js">// Accept-Encoding: gzip
this.acceptsEncodings(&#39;gzip&#39;, &#39;deflate&#39;, &#39;identity&#39;);
// =&gt; &quot;gzip&quot;

this.acceptsEncodings([&#39;gzip&#39;, &#39;deflate&#39;, &#39;identity&#39;]);
// =&gt; &quot;gzip&quot;</code></pre>
<p>  When no arguments are given all accepted encodings
  are returned as an array:</p>
<pre><code class="lang-js">// Accept-Encoding: gzip, deflate
this.acceptsEncodings();
// =&gt; [&quot;gzip&quot;, &quot;deflate&quot;, &quot;identity&quot;]</code></pre>
<p>  Note that the <code>identity</code> encoding (which means no encoding) could be unacceptable if the client explicitly sends <code>identity;q=0</code>. Although this is an edge case, you should still handle the case where this method returns <code>false</code>.</p>
<h3 id="request-acceptscharsets-charsets-">request.acceptsCharsets(charsets)</h3>
<p>  Check if <code>charsets</code> are acceptable, returning
  the best match when true, otherwise <code>false</code>.</p>
<pre><code class="lang-js">// Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5
this.acceptsCharsets(&#39;utf-8&#39;, &#39;utf-7&#39;);
// =&gt; &quot;utf-8&quot;

this.acceptsCharsets([&#39;utf-7&#39;, &#39;utf-8&#39;]);
// =&gt; &quot;utf-8&quot;</code></pre>
<p>  When no arguments are given all accepted charsets
  are returned as an array:</p>
<pre><code class="lang-js">// Accept-Charset: utf-8, iso-8859-1;q=0.2, utf-7;q=0.5
this.acceptsCharsets();
// =&gt; [&quot;utf-8&quot;, &quot;utf-7&quot;, &quot;iso-8859-1&quot;]</code></pre>
<h3 id="request-acceptslanguages-langs-">request.acceptsLanguages(langs)</h3>
<p>  Check if <code>langs</code> are acceptable, returning
  the best match when true, otherwise <code>false</code>.</p>
<pre><code class="lang-js">// Accept-Language: en;q=0.8, es, pt
this.acceptsLanguages(&#39;es&#39;, &#39;en&#39;);
// =&gt; &quot;es&quot;

this.acceptsLanguages([&#39;en&#39;, &#39;es&#39;]);
// =&gt; &quot;es&quot;</code></pre>
<p>  When no arguments are given all accepted languages
  are returned as an array:</p>
<pre><code class="lang-js">// Accept-Language: en;q=0.8, es, pt
this.acceptsLanguages();
// =&gt; [&quot;es&quot;, &quot;pt&quot;, &quot;en&quot;]</code></pre>
<h3 id="request-idempotent">request.idempotent</h3>
<p>  Check if the request is idempotent.</p>
<h3 id="request-socket">request.socket</h3>
<p>  Return the request socket.</p>
<h3 id="request-get-field-">request.get(field)</h3>
<p>  Return request header.</p>
</div></section><section><div class="content"><h1 id="response">Response</h1>
<p>  A Koa <code>Response</code> object is an abstraction on top of node&#39;s vanilla response object,
  providing additional functionality that is useful for every day HTTP server
  development.</p>
<h2 id="api">API</h2>
<h3 id="response-header">response.header</h3>
<p>  Response header object.</p>
<h3 id="response-headers">response.headers</h3>
<p>  Response header object. Alias as <code>response.header</code>.</p>
<h3 id="response-socket">response.socket</h3>
<p>  Request socket.</p>
<h3 id="response-status">response.status</h3>
<p>  Get response status. By default, <code>response.status</code> is not set unlike node&#39;s <code>res.statusCode</code> which defaults to <code>200</code>.</p>
<h3 id="response-status-">response.status=</h3>
<p>  Set response status via numeric code:</p>
<ul>
<li>100 &quot;continue&quot;</li>
<li>101 &quot;switching protocols&quot;</li>
<li>102 &quot;processing&quot;</li>
<li>200 &quot;ok&quot;</li>
<li>201 &quot;created&quot;</li>
<li>202 &quot;accepted&quot;</li>
<li>203 &quot;non-authoritative information&quot;</li>
<li>204 &quot;no content&quot;</li>
<li>205 &quot;reset content&quot;</li>
<li>206 &quot;partial content&quot;</li>
<li>207 &quot;multi-status&quot;</li>
<li>300 &quot;multiple choices&quot;</li>
<li>301 &quot;moved permanently&quot;</li>
<li>302 &quot;moved temporarily&quot;</li>
<li>303 &quot;see other&quot;</li>
<li>304 &quot;not modified&quot;</li>
<li>305 &quot;use proxy&quot;</li>
<li>307 &quot;temporary redirect&quot;</li>
<li>400 &quot;bad request&quot;</li>
<li>401 &quot;unauthorized&quot;</li>
<li>402 &quot;payment required&quot;</li>
<li>403 &quot;forbidden&quot;</li>
<li>404 &quot;not found&quot;</li>
<li>405 &quot;method not allowed&quot;</li>
<li>406 &quot;not acceptable&quot;</li>
<li>407 &quot;proxy authentication required&quot;</li>
<li>408 &quot;request time-out&quot;</li>
<li>409 &quot;conflict&quot;</li>
<li>410 &quot;gone&quot;</li>
<li>411 &quot;length required&quot;</li>
<li>412 &quot;precondition failed&quot;</li>
<li>413 &quot;request entity too large&quot;</li>
<li>414 &quot;request-uri too large&quot;</li>
<li>415 &quot;unsupported media type&quot;</li>
<li>416 &quot;requested range not satisfiable&quot;</li>
<li>417 &quot;expectation failed&quot;</li>
<li>418 &quot;i&#39;m a teapot&quot;</li>
<li>422 &quot;unprocessable entity&quot;</li>
<li>423 &quot;locked&quot;</li>
<li>424 &quot;failed dependency&quot;</li>
<li>425 &quot;unordered collection&quot;</li>
<li>426 &quot;upgrade required&quot;</li>
<li>428 &quot;precondition required&quot;</li>
<li>429 &quot;too many requests&quot;</li>
<li>431 &quot;request header fields too large&quot;</li>
<li>500 &quot;internal server error&quot;</li>
<li>501 &quot;not implemented&quot;</li>
<li>502 &quot;bad gateway&quot;</li>
<li>503 &quot;service unavailable&quot;</li>
<li>504 &quot;gateway time-out&quot;</li>
<li>505 &quot;http version not supported&quot;</li>
<li>506 &quot;variant also negotiates&quot;</li>
<li>507 &quot;insufficient storage&quot;</li>
<li>509 &quot;bandwidth limit exceeded&quot;</li>
<li>510 &quot;not extended&quot;</li>
<li>511 &quot;network authentication required&quot;</li>
</ul>
<p><strong>NOTE</strong>: don&#39;t worry too much about memorizing these strings,
if you have a typo an error will be thrown, displaying this list
so you can make a correction.</p>
<h3 id="response-message">response.message</h3>
<p>  Get response status message. By default, <code>response.message</code> is
  associated with <code>response.status</code>.</p>
<h3 id="response-message-">response.message=</h3>
<p>  Set response status message to the given value.</p>
<h3 id="response-length-">response.length=</h3>
<p>  Set response Content-Length to the given value.</p>
<h3 id="response-length">response.length</h3>
<p>  Return response Content-Length as a number when present, or deduce
  from <code>this.body</code> when possible, or <code>undefined</code>.</p>
<h3 id="response-body">response.body</h3>
<p>  Get response body.</p>
<h3 id="response-body-">response.body=</h3>
<p>  Set response body to one of the following:</p>
<ul>
<li><code>string</code> written</li>
<li><code>Buffer</code> written</li>
<li><code>Stream</code> piped</li>
<li><code>Object</code> json-stringified</li>
<li><code>null</code> no content response</li>
</ul>
<p>If <code>response.status</code> has not been set, Koa will automatically set the status to <code>200</code> or <code>204</code>.</p>
<h4 id="string">String</h4>
<p>  The Content-Type is defaulted to text/html or text/plain, both with
  a default charset of utf-8. The Content-Length field is also set.</p>
<h4 id="buffer">Buffer</h4>
<p>  The Content-Type is defaulted to application/octet-stream, and Content-Length
  is also set.</p>
<h4 id="stream">Stream</h4>
<p>  The Content-Type is defaulted to application/octet-stream.</p>
<h4 id="object">Object</h4>
<p>  The Content-Type is defaulted to application/json.</p>
<h3 id="response-get-field-">response.get(field)</h3>
<p>  Get a response header field value with case-insensitive <code>field</code>.</p>
<pre><code class="lang-js">var etag = this.get(&#39;ETag&#39;);</code></pre>
<h3 id="response-set-field-value-">response.set(field, value)</h3>
<p>  Set response header <code>field</code> to <code>value</code>:</p>
<pre><code class="lang-js">this.set(&#39;Cache-Control&#39;, &#39;no-cache&#39;);</code></pre>
<h3 id="response-append-field-value-">response.append(field, value)</h3>
<p>  Append additional header <code>field</code> with value <code>val</code>.</p>
<pre><code class="lang-js">this.append(&#39;Link&#39;, &#39;&lt;http://127.0.0.1/&gt;&#39;);</code></pre>
<h3 id="response-set-fields-">response.set(fields)</h3>
<p>  Set several response header <code>fields</code> with an object:</p>
<pre><code class="lang-js">this.set({
  &#39;Etag&#39;: &#39;1234&#39;,
  &#39;Last-Modified&#39;: date
});</code></pre>
<h3 id="response-remove-field-">response.remove(field)</h3>
<p>  Remove header <code>field</code>.</p>
<h3 id="response-type">response.type</h3>
<p>  Get response <code>Content-Type</code> void of parameters such as &quot;charset&quot;.</p>
<pre><code class="lang-js">var ct = this.type;
// =&gt; &quot;image/png&quot;</code></pre>
<h3 id="response-type-">response.type=</h3>
<p>  Set response <code>Content-Type</code> via mime string or file extension.</p>
<pre><code class="lang-js">this.type = &#39;text/plain; charset=utf-8&#39;;
this.type = &#39;image/png&#39;;
this.type = &#39;.png&#39;;
this.type = &#39;png&#39;;</code></pre>
<p>  Note: when appropriate a <code>charset</code> is selected for you, for
  example <code>response.type = &#39;html&#39;</code> will default to &quot;utf-8&quot;, however
  when explicitly defined in full as <code>response.type = &#39;text/html&#39;</code>
  no charset is assigned.</p>
<h3 id="response-is-types-">response.is(types...)</h3>
<p>  Very similar to <code>this.request.is()</code>.
  Check whether the response type is one of the supplied types.
  This is particularly useful for creating middleware that
  manipulate responses.</p>
<p>  For example, this is a middleware that minifies
  all HTML responses except for streams.</p>
<pre><code class="lang-js">var minify = require(&#39;html-minifier&#39;);

app.use(function *minifyHTML(next){
  yield next;

  if (!this.response.is(&#39;html&#39;)) return;

  var body = this.body;
  if (!body || body.pipe) return;

  if (Buffer.isBuffer(body)) body = body.toString();
  this.body = minify(body);
});</code></pre>
<h3 id="response-redirect-url-alt-">response.redirect(url, [alt])</h3>
<p>  Perform a [302] redirect to <code>url</code>.</p>
<p>  The string &quot;back&quot; is special-cased
  to provide Referrer support, when Referrer
  is not present <code>alt</code> or &quot;/&quot; is used.</p>
<pre><code class="lang-js">this.redirect(&#39;back&#39;);
this.redirect(&#39;back&#39;, &#39;/index.html&#39;);
this.redirect(&#39;/login&#39;);
this.redirect(&#39;http://google.com&#39;);</code></pre>
<p>  To alter the default status of <code>302</code>, simply assign the status
  before or after this call. To alter the body, assign it after this call:</p>
<pre><code class="lang-js">this.status = 301;
this.redirect(&#39;/cart&#39;);
this.body = &#39;Redirecting to shopping cart&#39;;</code></pre>
<h3 id="response-attachment-filename-">response.attachment([filename])</h3>
<p>  Set <code>Content-Disposition</code> to &quot;attachment&quot; to signal the client
  to prompt for download. Optionally specify the <code>filename</code> of the
  download.</p>
<h3 id="response-headersent">response.headerSent</h3>
<p>  Check if a response header has already been sent. Useful for seeing
  if the client may be notified on error.</p>
<h3 id="response-lastmodified">response.lastModified</h3>
<p>  Return the <code>Last-Modified</code> header as a <code>Date</code>, if it exists.</p>
<h3 id="response-lastmodified-">response.lastModified=</h3>
<p>  Set the <code>Last-Modified</code> header as an appropriate UTC string.
  You can either set it as a <code>Date</code> or date string.</p>
<pre><code class="lang-js">this.response.lastModified = new Date();</code></pre>
<h3 id="response-etag-">response.etag=</h3>
<p>  Set the ETag of a response including the wrapped <code>&quot;</code>s.
  Note that there is no corresponding <code>response.etag</code> getter.</p>
<pre><code class="lang-js">this.response.etag = crypto.createHash(&#39;md5&#39;).update(this.body).digest(&#39;hex&#39;);</code></pre>
<h3 id="response-vary-field-">response.vary(field)</h3>
<p>  Vary on <code>field</code>.</p>
</div></section><section><div class="content"><h1 id="links">Links</h1><p>Community links to discover third-party middleware for Koa, full runnable examples,
thorough guides and more! If you have questions join us in IRC!
</p><ul><li><a href="https://github.com/koajs/koa">GitHub repository</a></li><li><a href="https://github.com/koajs/examples">Examples</a></li><li><a href="https://github.com/koajs/koa/wiki">Middleware</a></li><li><a href="https://github.com/koajs/koa/wiki">Wiki</a></li><li><a href="https://plus.google.com/communities/101845768320796750641">G+ Community</a></li><li><a href="https://groups.google.com/forum/#!forum/koajs">Mailing list</a></li><li><a href="https://github.com/koajs/koa/blob/master/docs/guide.md">Guide</a></li><li><a href="https://github.com/koajs/koa/blob/master/docs/faq.md">FAQ</a></li><li><strong>#koajs</strong> on freenode</li></ul></div></section></body></html>